<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: Todo List</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div><div class="header">
  <div class="headertitle"><div class="title">Todo List </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><dl class="reflist">
<dt>Page <a class="el" href="async_loop.html">Asynchronicity and Integrating with Your Event Loop</a>  </dt>
<dd><a class="anchor" id="_todo000042"></a>We may supply an alternative API wherein Flow-IPC objects can be boost.asio I/O objects themselves, similarly to <code>boost::asio::ip::tcp::socket</code>. </dd>
<dt>Member <a class="el" href="classipc_1_1session_1_1Client__session__impl.html#a6c67f6c993089dadf16acb47d535cb68">ipc::session::Client_session_impl&lt; S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_GRACEFUL_FINISH_REQUIRED_V &gt;::create_channel_obj</a>  (const Shared_name &amp;mq_name_c2s_or_none, const Shared_name &amp;mq_name_s2c_or_none, <a class="el" href="structipc_1_1util_1_1Native__handle.html" title="A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.">util::Native_handle</a> &amp;&amp;local_hndl_or_null, Channel_obj *opened_channel_ptr, bool active_else_passive, Error_code *err_code_ptr)</dt>
<dd><a class="anchor" id="_todo000033"></a>As of this writing the eventuality where <a class="el" href="classipc_1_1session_1_1Client__session__impl.html#a6c67f6c993089dadf16acb47d535cb68" title="In thread W, based on resources acquired on server side, creates local Channel_obj to emit to the use...">Client_session_impl::create_channel_obj()</a> yields an error is treated as assertion-trip-worthy by its caller; hence consider just tripping assertion inside instead and no out-arg. For now it is left this way in case we'd want the (internal) caller to do something more graceful in the future, and in the meantime it's a decently reusable chunk of code to use in that alleged contingency.  </dd>
<dt>Member <a class="el" href="classipc_1_1session_1_1Client__session__mv.html#ab971ea979200828d572638c60d7d9f44">ipc::session::Client_session_mv&lt; Client_session_impl_t &gt;::sync_connect</a>  (Error_code *err_code=0)</dt>
<dd><a class="anchor" id="_todo000032"></a>Consider adding an optional mode/feature to allow to wait through the condition wherein CNS (PID) file does not exist, or it does but the initial session-open connect op would be refused; instead it detects these relatively common conditions (server not yet up and/or is restarting and/or is operationally suspended for now, etc.) as normal and waits until the condition is cleared. Without this mode, a typical user would probably do something like: oh, <a class="el" href="classipc_1_1session_1_1Client__session__mv.html#ab971ea979200828d572638c60d7d9f44" title="To be invoked in NULL state only, and not as-if default-cted, it synchronously and non-blockingly att...">sync_connect()</a> failed; let's sleep 1 sec and try again (rinse/repeat). It's not awful, but we might as well make it easier and more responsive out of the box (optionally). Upon resolving this to-do please update the Manual section <a class="el" href="session_setup.html">Sessions: Setting Up an IPC Context</a> accordingly. </dd>
<dt>Class <a class="el" href="classipc_1_1session_1_1Session__base_1_1Graceful__finisher.html">ipc::session::Session_base&lt; S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload &gt;::Graceful_finisher</a>  </dt>
<dd><a class="anchor" id="_todo000034"></a>Consider how to avoid having SHM-jemalloc <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> mechanism require one side's <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> dtor await (and possibly block) the start of the opposing side's <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> dtor, before it can proceed. The reason it does this today is above this to-do in the code. The blocking is not too bad &ndash; if the user's applications are properly written, it will not occur, and the existing logging should make clear why it happens, if it happens; but it's still not ideal. There are a couple known mitigating approaches, and at least 1 ticket covering them is likely filed. (Either way the <a class="el" href="classipc_1_1session_1_1Session__base_1_1Graceful__finisher.html" title="Optional to use by subclasses, this operates a simple state machine that carries out a graceful-sessi...">Graceful_finisher</a> mechanism could then be removed probably.) To summarize them: 1, there can be a mechanism deep inside SHM-jemalloc code that gives (arbitrarily long, configurable) grace period for known borrowed objects whose session channels have closed before those objects were returned; this was echan's idea on this topic. Once the grace period is reached, it would act as-if they got returned then (so in the above scenario the arena could get jemalloc-deinitialized and all). If program needs to exit, it could either block until the end of the grace period or... who knows? 2, something similar could be done about the SHM-internal-use channel: do not close it but add it to some list of such channels; they would be finally closed upon detection of the other side's <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code> dtor being reached, in some background thread somewhere. (On 2nd thought this sounds a lot like <a class="el" href="classipc_1_1session_1_1Session__base_1_1Graceful__finisher.html" title="Optional to use by subclasses, this operates a simple state machine that carries out a graceful-sessi...">Graceful_finisher</a> &ndash; but for this particular internal-use channel only. The code here would only get more complex, thought maybe not too much more. However, it would resolve the observed <code><a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a></code>-dtor-blocking user-visible issue, at least until the delayed-channel-death process had to exit entirely.) Beyond these basic ideas (which could even perhaps be combined) this requires some thinking; it is an interesting problem. In the meantime the dtor-cross-process-barrier-of-sorts existing solution is pretty decent. </dd>
<dt>Class <a class="el" href="classipc_1_1session_1_1Session__server__impl.html">ipc::session::Session_server_impl&lt; Session_server_t, Server_session_t &gt;</a>  </dt>
<dd><a class="anchor" id="_todo000035"></a><a class="el" href="classipc_1_1session_1_1Session__server.html" title="To be instantiated typically once in a given process, an object of this type asynchronously listens f...">Session_server</a>, probably in ctor or similar, should &ndash; for safety &ndash; enforce the accuracy of <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a> attributes including <a class="el" href="structipc_1_1session_1_1App.html#ae82a8635858664720c8546e468f8090b" title="Absolute, lexically normalized canonical path to the executable entity (which is not a directory),...">App::m_exec_path</a>, <a class="el" href="structipc_1_1session_1_1App.html#a9e32297579603f2d96616976474d0246" title="The application must run as this user ID (UID). Files and other shared resources shall have this owne...">App::m_user_id</a>, <a class="el" href="structipc_1_1session_1_1App.html#a78bb1e984835f429fd44869a83f4b093" title="The application must run as this group ID (GID). Files and other shared resources shall have this own...">App::m_group_id</a>. As of this writing it enforces these things about each <em>opposing</em> <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> and process &ndash; so for sanity it can/should do so about itself, before the sessions can begin. </dd>
<dt>Member <a class="el" href="classipc_1_1session_1_1Session__server__impl.html#ad7cd4d77db826af9fe39c17e8ee7ca37">ipc::session::Session_server_impl&lt; Session_server_t, Server_session_t &gt;::this_session_srv</a>  ()</dt>
<dd><a class="anchor" id="_todo000036"></a>Reconsider the details of how classes in the non-<code>virtual</code> hierarchies <code><a class="el" href="classipc_1_1session_1_1Session__server.html" title="To be instantiated typically once in a given process, an object of this type asynchronously listens f...">Session_server</a></code>, <code>Server_session</code>, <code><a class="el" href="classipc_1_1session_1_1Session__server__impl.html" title="Internal class template comprising API/logic common to every Session_server variant,...">Session_server_impl</a></code>, <code><a class="el" href="classipc_1_1session_1_1Server__session__impl.html" title="Internal, non-movable pImpl-lite implementation of Server_session_mv class template.">Server_session_impl</a></code> cooperate internally, as there is some funky stuff going on, particularly <a class="el" href="classipc_1_1session_1_1Session__server__impl.html#ad7cd4d77db826af9fe39c17e8ee7ca37" title="Returns pointer to the object that is privately sub-classing us.">Session_server_impl::this_session_srv()</a>. </dd>
<dt>Member <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend_1_1jemalloc_1_1error.html#a9723fe7e789d5d2d670c42d32238f223a9fcf37ffabb8e0b552276e4bcbe5b0e0">ipc::session::shm::arena_lend::jemalloc::error::S_SHM_ARENA_CREATION_FAILED</a>  </dt>
<dd><a class="anchor" id="_todo000040"></a>If ipc::shm::arena_lend arena-creation API(s) are modified to output an <code>Error_code</code> instead of reporting just success-versus-failure, then ipc::session::error::Code::S_SHM_ARENA_CREATION_FAILED should go away.  </dd>
<dt>Member <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend_1_1jemalloc_1_1error.html#a9723fe7e789d5d2d670c42d32238f223a04f63ffadacfeb4386f846615587aa41">ipc::session::shm::arena_lend::jemalloc::error::S_SHM_ARENA_LEND_FAILED</a>  </dt>
<dd><a class="anchor" id="_todo000041"></a>If ipc::shm::arena_lend arena-lending API(s) are modified to output an <code>Error_code</code> instead of reporting just success-versus-failure and reporting problem through an async callback, then ipc::session::error::Code::S_SHM_ARENA_CREATION_FAILED should go away. See shm::arena_lend::jemalloc::init_shm() body for more discussion.  </dd>
<dt>Class <a class="el" href="classipc_1_1session_1_1sync__io_1_1Client__session__adapter.html">ipc::session::sync_io::Client_session_adapter&lt; Session &gt;</a>  </dt>
<dd><a class="anchor" id="_todo000037"></a>Make all of <a class="el" href="classipc_1_1session_1_1sync__io_1_1Server__session__adapter.html" title="sync_io-pattern counterpart to async-I/O-pattern session::Server_session types and all their SHM-awar...">Server_session_adapter</a>, <a class="el" href="classipc_1_1session_1_1sync__io_1_1Client__session__adapter.html" title="sync_io-pattern counterpart to async-I/O-pattern session::Client_session types and all their SHM-awar...">Client_session_adapter</a> move-ctible/assignable like their adapted counterparts. It is not of utmost importance practically, unlike for the adapter guys, but at least for consistency it would be good; and of course it never hurts usability even if not critical. (Internally: This is not difficult to implement; the async-I/O guys being movable was really the hard part.) </dd>
<dt>Class <a class="el" href="classipc_1_1shm_1_1stl_1_1Stateless__allocator.html">ipc::shm::stl::Stateless_allocator&lt; T, Arena &gt;</a>  </dt>
<dd><a class="anchor" id="_todo000038"></a>Currently <code>Arena::Pointer</code> shall be a fancy-pointer, but we could support raw pointers also. Suppose <a class="el" href="classipc_1_1shm_1_1stl_1_1Stateless__allocator.html#ab8733c1237be93ee28664e4b983d535c" title="Short-hand for the Arena type this uses for allocation/deallocation/pointer semantics.">Arena_obj</a> is set up in such a way as to map all processes' locally-dereferenceable pointers to the same SHM location to the same numeric value (by specifying each pool's start as some predetermined numerical value in the huge 64-bit vaddr space &ndash; in all processes sharing that SHM pool. Now no address translation is needed, and <code>Arena::Pointer</code> could be simply <code>T*</code>. As of this writing some inner impl details suppose it being a fancy-pointer, and it's the only active need we have; but that could be tweaked with a bit of effort. </dd>
<dt>Namespace <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html">ipc::transport::asio_local_stream_socket</a>  </dt>
<dd><p class="startdd"><a class="anchor" id="_todo000002"></a><code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> additional feature: APIs that can read and write native sockets together with accompanying binary blobs can be extended to handle an arbitrary number of native handles (per call) as opposed to only 0 or 1. The main difficulty here is designing a convenient and stylish, yet performant, API.</p>
<p class="interdd"><a class="anchor" id="_todo000001"></a>At least <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html#acf7bdf0c727cbf0c5297125c762e1001" title="boost.asio extension similar to boost::asio::async_read(Peer_socket&amp;, Blob_mutable,...">asio_local_stream_socket::async_read_with_target_func()</a> can be extended to other stream sockets (TCP, etc.). In that case it should be moved to a different namespace however (perhaps named <code>asio_stream_socket</code>; could then move the existing <code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> inside that one and rename it <code>local</code>).</p>
<p class="interdd"><a class="anchor" id="_todo000003"></a><code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> additional feature: APIs that can read and write native handles together with accompanying binary blobs can be extended to handle scatter/gather semantics for the aforementioned blobs, matching standard boost.asio API functionality.</p>
<p class="interdd"><a class="anchor" id="_todo000004"></a><code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> additional feature: Non-blocking APIs like <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html#a9ae82b2a234b218704c62fb616d6fcc5" title="boost.asio extension similar to peer_socket-&gt;non_blocking(true); auto n = peer_socket-&gt;read_some(targ...">nb_read_some_with_native_handle()</a> and <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html#a1022dfd42e9a0d6eab8384b0352decb0" title="boost.asio extension similar to peer_socket-&gt;non_blocking(true); auto n = peer_socket-&gt;write_some(pay...">nb_write_some_with_native_handle()</a> can gain blocking counterparts, matching standard boost.asio API functionality.</p>
<p class="interdd"><a class="anchor" id="_todo000005"></a><code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> additional feature: <code>async_read_some_with_native_handle()</code> &ndash; async version of existing <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html#a9ae82b2a234b218704c62fb616d6fcc5" title="boost.asio extension similar to peer_socket-&gt;non_blocking(true); auto n = peer_socket-&gt;read_some(targ...">nb_read_some_with_native_handle()</a>. Or another way to put it is, equivalent of boost.asio <code>Peer_socket::async_read_some()</code> but able to read native handle(s) with the blob. Note: This API would potentially be usable inside the impl of existing APIs (code reuse).</p>
<p class="enddd"><a class="anchor" id="_todo000006"></a><code><a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html" title="Additional (versus boost.asio) APIs for advanced work with local stream (Unix domain) sockets includi...">asio_local_stream_socket</a></code> additional feature: <code>async_read_with_native_handle()</code> &ndash; async version of existing <a class="el" href="namespaceipc_1_1transport_1_1asio__local__stream__socket.html#a9ae82b2a234b218704c62fb616d6fcc5" title="boost.asio extension similar to peer_socket-&gt;non_blocking(true); auto n = peer_socket-&gt;read_some(targ...">nb_read_some_with_native_handle()</a>, plus the "stubborn" behavior of built-in <code>async_read()</code> free function. Or another way to put it is, equivalent of boost.asio <code>async_read&lt;Peer_socket&gt;()</code> but able to read native handle(s) with the blob. Note: This API would potentially be usable inside the impl of existing APIs (code reuse). </p>
</dd>
<dt>Namespace <a class="el" href="namespaceipc_1_1transport_1_1error.html">ipc::transport::error</a>  </dt>
<dd><a class="anchor" id="_todo000007"></a>This file and error.cpp are perfectly reasonable and worth-it and standard boiler-plate; and it's not that lengthy really; but it'd be nice to stop having to copy/paste all the stuff outside of just the error codes and messages. Should add a feature to Flow that'll reduce the boiler-plate to just that; maybe some kind of base class or something. <a class="el" href="namespaceboost_1_1system.html" title="Small group of miscellaneous utilities to ease work with boost.system, joining its boost::system name...">boost.system</a> already makes it pretty easy, but even that can probably be "factored out" into Flow. Update: I (ygoldfel) took a look at it for another project, and so far no obvious de-boiler-plate ideas come to mind. Ideally the inputs are: (1) an <code>enum</code> with the codes, like <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297" title="All possible errors returned (via Error_code arguments) by ipc::transport functions/methods outside o...">error::Code</a>; (2) an <code>int</code>-to-<code>string</code> message table function, for log messages; and (3) a brief <code>const char*</code> identifying the code set, for log messages. The rest is the boiler-plate, but all of it seems to either already be accepably brief, and where something isn't quite so, I can't think of any obvious way to factor it out. Of course a macro-based "meta-language" is always a possibility, as we did in <code>flow::log</code>, but in this case it doesn't seem worth it at all.  </dd>
<dt>Class <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">ipc::transport::Native_handle_sender</a>  </dt>
<dd><p class="startdd"><a class="anchor" id="_todo000008"></a>In C++20, if/when we upgrade to that, <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (and other such doc-only classes) can become an actual concept formally implemented by class(es) that, today, implement it via the "honor system." Currently it is a class <code>#ifdef</code>-ed out from actual compilation but still participating in doc generation. Note that Doxygen (current version as of this writing: 1.9.3) claims to support doc generation from formal C++20 concepts.</p>
<p class="enddd"><a class="anchor" id="_todo000009"></a>Comparing <a class="el" href="classipc_1_1transport_1_1Blob__sender.html#af5d889f8a209353b3d69f70b44a2095c" title="In PEER state: Returns max blob.size() such that send_blob() shall not fail due to too-long payload w...">Blob_sender::send_blob_max_size()</a> (and similar checks in that family of concepts) to test whether the object is in PEER state is easy enough, but perhaps we can have a utility that would more expressively describe this check: <code>in_peer_state()</code> free function or something? It can still use the same technique internally.  </p>
</dd>
<dt>Class <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html">ipc::transport::Native_socket_stream_acceptor</a>  </dt>
<dd><a class="anchor" id="_todo000010"></a>At the moment, <em>if</em> one decides to use a <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html" title="A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...">Native_socket_stream_acceptor</a> directly &ndash; not really necessary given <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> <code><a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">Channel</a></code>-opening capabilities &ndash; the the user must come up with their own naming scheme that avoids name clashes; we could supply an <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>-facilitated system for providing this service instead. I.e., <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> could either expose a facility for generating the <code>Shared_name absolute_name</code> arg to the <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html" title="A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...">Native_socket_stream_acceptor</a> ctor (and opposing <a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html#a89d591db714e83dcb55a52738fed1ebb" title="To be invoked in NULL state only, it synchronously and non-blockingly attempts to connect to an oppos...">Native_socket_stream::sync_connect()</a> call). Alternatively it could provide some kind of <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html" title="A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...">Native_socket_stream_acceptor</a> factory and corresponding opposing facility. Long story short, within the <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> way of life literally only one acceptor exists, and it is set up (and named) internally to <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>. We could provide a way to facilitate the creation of more acceptors if desired by helping to choose their <code>Shared_name</code>s. (An original "paper" design did specify a naming scheme for this.) </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html#a7928656e82682f101af9a2fd6d4019cc">ipc::transport::Native_socket_stream_acceptor::m_next_peer_socket</a>  </dt>
<dd><a class="anchor" id="_todo000011"></a>Perform a rigorous analysis of the perf and style trade-offs between move-construction-based patterns versus <code>shared_ptr</code>-based ones, possibly focusing on boost.asio socket objects in particular.  </dd>
<dt>Class <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html">ipc::transport::struc::Channel&lt; Channel_obj, Message_body, Struct_builder_config, Struct_reader_config &gt;</a>  </dt>
<dd><p class="startdd"><a class="anchor" id="_todo000023"></a>Consider adding the <em>optional</em> expectation of a particular <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#ac2a3a80151886bec41f3fc3a8880e384" title="Stylistic nicety, indicating that a Msg_which applies to an in-message rather than an out-message.">Msg_which_in</a> when registering expected responses in <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#a97506bcb695f22e7ca6b480bae5b2346" title="Identical to send() sends the out-message not as a notification but as a request, registering the exp...">struc::Channel::async_request()</a>.</p>
<p class="enddd"><a class="anchor" id="_todo000024"></a><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a> should probably be made move-constructible and move-assignable. No concept requires this, unlike with many other classes and class templates in <a class="el" href="namespaceipc.html" title="Catch-all namespace for the Flow-IPC project: A library/API in modern C++17 providing high-performanc...">ipc</a>, so it is less essential; but both for consistency and usability it would be good. It would also make some APIs possible that currently would require the user to explicitly wrap this class in a <code>unique_ptr</code>. For example, imagine a <code>Session::Structured_channel Session::structured_channel_upgrade(Channel_obj&amp;&amp; channel, ...)</code> that constructs a suitably-typed <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a>, subsuming the raw <code>channel</code> just opened in that <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">session::Session</a>, and returns that guy. Currently it would need to return <code>unique_ptr&lt;Session::Structured_channel&gt;</code> or something. </p>
</dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab08057edd9832d94ea0e18a17c42200a">ipc::transport::struc::Channel&lt; Channel_obj, Message_body, Struct_builder_config, Struct_reader_config &gt;::async_end_sending</a>  (Task_err &amp;&amp;on_done_func)</dt>
<dd><a class="anchor" id="_todo000028"></a>Consider adding blocking <code>struc::Channel::sync_end_sending()</code>, possibly with timeout, since <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#ab08057edd9832d94ea0e18a17c42200a" title="Operating at the unstructured layer, executes a graceful-close send by forwarding to the async transp...">async_end_sending()</a></code> to completion is recommended (but not required) to execute at EOL of any <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a>. The "blocking" part is good because it's convenient to not have to worry about handling completion with async semantics boiler-plate. The "timeout" part is good because it's a best-effort operation, when in a bad/slow environment, and blocking &ndash; even during deinit &ndash; would be important to avoid. For example, the <code>Session</code> impls' dtors perform this op; we don't want those to block for any significant time if at all avoidable. The reason it's a mere to-do currently is that a bug-free opposing <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a> should not let would-block occur for any real length of time; so blocking is presumably unlikely. Nevertheless. </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#af9130e43dc985fca4a41f19581048b51">ipc::transport::struc::Channel&lt; Channel_obj, Message_body, Struct_builder_config, Struct_reader_config &gt;::owned_channel_mutable</a>  ()</dt>
<dd><a class="anchor" id="_todo000026"></a>Consider adding <code>struc::Channel::auto_ping()</code> and <code>struc::Channel::idle_timer_run()</code> and, for safety, removing <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#af9130e43dc985fca4a41f19581048b51" title="Access to mutable transport::Channel moved-into *this at construction.">struc::Channel::owned_channel_mutable()</a>. </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#a18100e5af4f5111f1515ff9eef8b1f92">ipc::transport::struc::Channel&lt; Channel_obj, Message_body, Struct_builder_config, Struct_reader_config &gt;::sync_request</a>  (const <a class="el" href="classipc_1_1transport_1_1struc_1_1Msg__out.html" title="A structured out-message suitable to be sent via struc::Channel::send() (et al).">Msg_out</a> &amp;msg, const <a class="el" href="classipc_1_1transport_1_1struc_1_1Msg__in.html" title="A structured in-message instance suitable as received and emittable (to user) by struc::Channel.">Msg_in</a> *originating_msg_or_null, <a class="el" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58" title="Short-hand for Flow&#39;s Fine_duration.">util::Fine_duration</a> timeout, Error_code *err_code)</dt>
<dd><a class="anchor" id="_todo000027"></a>Improve <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#aa41aee3c76035f43833078e625e6ef78" title="Equivalent to the other sync_request() overload but with no timeout; meaning it shall exit only once ...">ipc::transport::struc::Channel::sync_request()</a>, so that 2 such calls on the same <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">Channel</a></code> can execute without one having to fully block the other. Note this may be seen as a <em>breaking change</em> of sorts for the purposes of release notes (even though it would presumably be seen as an improvement). </dd>
<dt>Class <a class="el" href="classipc_1_1transport_1_1struc_1_1Msg__in__impl.html">ipc::transport::struc::Msg_in_impl&lt; Message_body, Struct_reader_config &gt;</a>  </dt>
<dd><a class="anchor" id="_todo000029"></a><a class="el" href="classipc_1_1transport_1_1struc_1_1Msg__in__impl.html" title="Internally used (data-free) addendum on-top of Msg_in which makes the protected API public instead.">Msg_in_impl</a> is pretty wordy; maybe <code>friend</code> would have been stylistically acceptable after all? It's so much briefer, and we could simply resolve to only access the <code>protected</code> APIs and not <code>private</code> stuff....  </dd>
<dt>Member <a class="el" href="namespaceipc_1_1transport_1_1struc.html#a6751c05fb6582a34c7c47ac470c4a48b">ipc::transport::struc::Session_token</a>  </dt>
<dd><a class="anchor" id="_todo000030"></a>Look into whether something smaller that RFC 4122 UUIDs can and should be used for <a class="el" href="namespaceipc_1_1transport_1_1struc.html#a6751c05fb6582a34c7c47ac470c4a48b" title="A type used by struc::Channel for internal safety/security/auth needs.">Session_token</a>. This would be for perf but may well be unnecessary. See discussion near this to-do.  </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1struc_1_1shm_1_1Capnp__message__builder.html#adde965642bf6f38036dfc31f0b9e75f4">ipc::transport::struc::shm::Capnp_message_builder&lt; Shm_arena &gt;::lend</a>  (schema::detail::ShmTopSerialization::Builder *capnp_root, <a class="el" href="namespaceipc_1_1session_1_1shm.html#af2acc444cc9664e57df8143b66b78d70" title="Alias that, given an Arena type (with Arena::construct&lt;T&gt;() which allocates/constructs a T),...">session::shm::Arena_to_shm_session_t&lt; Arena &gt;</a> *shm_session)</dt>
<dd><a class="anchor" id="_todo000039"></a>Would be nice to provide a more-general counterpart to existing <a class="el" href="classipc_1_1transport_1_1struc_1_1shm_1_1Capnp__message__builder.html#adde965642bf6f38036dfc31f0b9e75f4" title="To be called after being done mutating underlying structured data, increments owner-process count by ...">Capnp_message_builder::lend()</a> (in addition to that one which outputs into a capnp structure), such as one that outputs a mere <code>Blob</code>. The existing one is suitable for the main use-case which is internally by <a class="el" href="classipc_1_1transport_1_1struc_1_1shm_1_1Builder.html" title="Implements Struct_builder concept with maximal zero-copy perf by (1) storing the actual user-schema-c...">shm::Builder</a>; but <a class="el" href="classipc_1_1transport_1_1struc_1_1shm_1_1Capnp__message__builder.html" title="A capnp::MessageBuilder used by shm::Builder: similar to a MallocMessageBuilder with the GROW_HEURIST...">Capnp_message_builder</a> is also usable as a <code>capnp::MessageBuilder</code> directly. If a user were to indeed leverage it in that latter capacity, they may want to transmit/store the SHM-handle some other way. Note that as of this writing the direct-use-by-general-user-as-<code>MessageBuilder</code> use-case is supported "just
because" it can be; nothing in particular needed it. </dd>
<dt>Class <a class="el" href="structipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_1_1Msg__in__pipe.html">ipc::transport::struc::sync_io::Channel&lt; Channel_obj, Message_body, Struct_builder_config, Struct_reader_config &gt;::Msg_in_pipe</a>  </dt>
<dd><a class="anchor" id="_todo000031"></a>Look into the algorithm documented in <a class="el" href="structipc_1_1transport_1_1struc_1_1sync__io_1_1Channel_1_1Msg__in__pipe.html" title="Data and policy with respect to receipt of the next/currently-incomplete in-message.">Channel::Msg_in_pipe</a> wherein (with 2 pipes in the channel) some low-level messages associated with handle-bearing user structured messages are sent over the (presumably somewhat slower) handles pipe despite, themselves, not containing a native handle being transmitted. See text just above this to-do in the code. </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Blob__stream__mq__receiver__impl.html#a9f1120b92ea20944b2de416d870644ce">ipc::transport::sync_io::Blob_stream_mq_receiver_impl&lt; Persistent_mq_handle &gt;::m_nb_task_engine</a>  </dt>
<dd><a class="anchor" id="_todo000012"></a>Consider using specialization instead of or in addition <code>if constexpr()</code> w/r/t <code>Mq::S_HAS_NATIVE_HANDLE</code>-based compile-time branching: it could save some RAM by eliminating <code>optional</code>s such as the one near this to-do; though code would likely become wordier.  </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Blob__stream__mq__receiver__impl.html#af308d3f1ff50138070c8422552f069a5">ipc::transport::sync_io::Blob_stream_mq_receiver_impl&lt; Persistent_mq_handle &gt;::m_target_control_blob</a>  </dt>
<dd><a class="anchor" id="_todo000013"></a>Maybe we should indeed use <code>m_user_request-&gt;m_target_blob</code> (instead of locally stored <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Blob__stream__mq__receiver__impl.html#af308d3f1ff50138070c8422552f069a5" title="Used only when m_control_state is true, this is where payload 2 (the Control_cmd) is placed.">m_target_control_blob</a>) to save RAM/a few cycles? Technically at least user should not care if some garbage is temporarily placed there (after PING a real message should arrive and replace it; or else on error or graceful-close who cares?).  </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Blob__stream__mq__sender__impl.html#a0614000879d4595c84f803ecadae708a">ipc::transport::sync_io::Blob_stream_mq_sender_impl&lt; Persistent_mq_handle &gt;::m_nb_task_engine</a>  </dt>
<dd><a class="anchor" id="_todo000014"></a>Consider using specialization instead of or in addition <code>if constexpr()</code> w/r/t <code>Mq::S_HAS_NATIVE_HANDLE</code>-based compile-time branching: it could save some RAM by eliminating <code>optional</code>s such as the one near this to-do; though code would likely become wordier.  </dd>
<dt>Class <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream_1_1Impl.html">ipc::transport::sync_io::Native_socket_stream::Impl</a>  </dt>
<dd><a class="anchor" id="_todo000015"></a>Internal <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream.html" title="Implements both sync_io::Native_handle_sender and sync_io::Native_handle_receiver concepts by using a...">Native_socket_stream</a> and <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream__acceptor.html" title="sync_io-pattern counterpart to async-I/O-pattern transport::Native_socket_stream_acceptor.">Native_socket_stream_acceptor</a> queue algorithms and data structures should be checked for RAM use; perhaps something should be periodically shrunk if applicable. Look for <code>vector</code>s, <code>deque</code>s (including inside <code>queue</code>s). </dd>
<dt>Member <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream_1_1Impl.html#a42aab631e9c70bfaa53764309adfe37c">ipc::transport::sync_io::Native_socket_stream::Impl::m_peer_socket</a>  </dt>
<dd><a class="anchor" id="_todo000016"></a><code>Peer_socket m_peer_socket</code> synchronous-read ops (<code>read_some()</code>) are actually documented in boost::asio to be thread-safe against concurrently invoked synchronous-write ops (<code>write_some()</code>), as are OS calls <code>"::recvmsg()"</code>, <code>"::sendmsg()"</code>; therefore for possible perf bump consider never nullifying <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream_1_1Impl.html#a42aab631e9c70bfaa53764309adfe37c" title="The peer stream-type Unix domain socket; or null pointer if we&#39;ve detected the connection has become ...">Impl::m_peer_socket</a>; eliminating <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream_1_1Impl.html#abc7d2b14208ed2b8c0add0c26f7fbf27" title="Protects m_peer_socket and its bros m_ev_wait_hndl_peer_socket and m_peer_socket_hosed.">Impl::m_peer_socket_mutex</a>; and letting each direction's logic discover any socket-error independently. (But, at the moment, <code>m_peer_socket_mutex</code> also covers mirror-guy <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream_1_1Impl.html#a0ac6a82eda9256cba45f3b5365d79355" title="Descriptor waitable by outside event loop async-waits – storing the same Native_handle as (and thus b...">m_ev_wait_hndl_peer_socket</a>, so that must be worked out.) </dd>
<dt>Class <a class="el" href="classipc_1_1util_1_1Default__init__allocator.html">ipc::util::Default_init_allocator&lt; T, Allocator &gt;</a>  </dt>
<dd><a class="anchor" id="_todo000017"></a><a class="el" href="classipc_1_1util_1_1Default__init__allocator.html" title="Allocator adaptor (useful for, e.g., vector that skips zero-filling) that turns a value-initializatio...">ipc::util::Default_init_allocator</a> should be moved into Flow's <code>flow::util</code>. </dd>
<dt>Member <a class="el" href="namespaceipc_1_1util.html#af7728c93fdf29479bbb2482e02f05cbf">ipc::util::operator&lt;&lt;</a>  (std::ostream &amp;os, const <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">Shared_name</a> &amp;val)</dt>
<dd><a class="anchor" id="_todo000021"></a>Does <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">Shared_name</a> <code>operator&gt;&gt;</code> and <code>operator&lt;&lt;</code> being asymmetrical get one into trouble when using <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">Shared_name</a> with boost.program_options (or <code>flow::cfg</code> which is built on top of it)? Look into it. It may be necessary to make <code>operator&lt;&lt;</code> equal to that of <code>ostream &lt;&lt; string</code> after all; though the added niceties of the current <code>&lt;&lt;</code> semantics may still at least be available via some explicit accessor. </dd>
<dt>Member <a class="el" href="classipc_1_1util_1_1Shared__name.html#a4ebeee7fd046ca6ad405af6183dfb790">ipc::util::Shared_name::m_raw_name</a>  </dt>
<dd><a class="anchor" id="_todo000020"></a>Consider providing a ref-to-mutable accessor to <a class="el" href="classipc_1_1util_1_1Shared__name.html#a4ebeee7fd046ca6ad405af6183dfb790" title="The name or name fragment; see str().">Shared_name::m_raw_name</a> (or just make <code>public</code>). There are pros and cons; the basic pro being that <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">Shared_name</a> is meant to be a very thin wrapper around <code>std::string</code>, so it might make sense to allow for in-place modification without supplying some kind of reduced subset of <code>string</code> API. Suggest doing this to-do if a practical desire comes about.  </dd>
<dt>Member <a class="el" href="classipc_1_1util_1_1Shared__name.html#afc9b87fc69d42df3107bf4a27ea66c7c">ipc::util::Shared_name::S_MAX_LENGTH</a>  </dt>
<dd><p class="startdd"><a class="anchor" id="_todo000019"></a>Research real limits on <a class="el" href="classipc_1_1util_1_1Shared__name.html#afc9b87fc69d42df3107bf4a27ea66c7c" title="Max value of size() such that, if str() used to name a supported shared resource, sys call safely won...">Shared_name::S_MAX_LENGTH</a> for different real resource types; choose something for MAX_LENGTH that leaves enough slack to avoid running into trouble when making actual sys calls; as discussed in the at-internal section of <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">Shared_name</a> doc header about this topic. Explain here how we get to the limit ultimately chosen. The limit as of this writing is 64, but real research is needed. </p>
<p class="enddd"><a class="anchor" id="_todo000018"></a><a class="el" href="classipc_1_1util_1_1Shared__name.html#afc9b87fc69d42df3107bf4a27ea66c7c" title="Max value of size() such that, if str() used to name a supported shared resource, sys call safely won...">Shared_name::S_MAX_LENGTH</a> currently applies to all shared resource types, but it'd be a useful feature to have different limits depending on OS/whatever limitations for particular resources types such as SHM object names versus queue names versus whatever. </p>
</dd>
<dt>Namespace <a class="el" href="namespaceipc_1_1util_1_1sync__io.html">ipc::util::sync_io</a>  </dt>
<dd><a class="anchor" id="_todo000022"></a>Write an example of <code><a class="el" href="namespaceipc_1_1util_1_1sync__io.html" title="Contains common code, as well as important explanatory documentation in the following text,...">sync_io</a></code>-pattern use with an old-school reactor-pattern event loop, using <code>poll()</code> and/or <code>epoll_*()</code>. </dd>
<dt>Member <a class="el" href="ipc__transport__structured_2src_2ipc_2transport_2struc_2channel_8hpp.html#a8646782bf9b3daa107f2aa818f6345cb">TEMPLATE_STRUCTURED_CHANNEL</a>  </dt>
<dd><a class="anchor" id="_todo000025"></a>Look over the rest of the code base &ndash; possibly in Flow too &ndash; and apply the <code>define TEMPLATE_</code><ul>
<li><code>define CLASS_</code> technique where it'd be subjectively beneficial. </li>
</ul>
</dd>
</dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:26 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
